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NAME 

name_to_handle_at, open_by_handle_at - obtain handle for a pathname and open file via a handle 

SYNOPSIS 

#define _GNU_SOURCE /* See feature_test_macros(7) */ 

#inelude <sys/types.h> 

#inelude <sys/stat.h> 

#inelude <fcntl.h> 

int name_to_handle_at(int dirfd, const char * pathname, 
struct file_handle * handle, 
int * mountJd, int flags); 

int open_by_handle_at(int mount Jd, struct file_handle * handle, 
int flags); 

DESCRIPTION 

The name_to_handle_at() and open_by_handle_at() system calls split the functionality of openat(2) into 
two parts: name_to_handle_at() returns an opaque handle that corresponds to a specified file; 
open_by_handle_at() opens the file corresponding to a handle returned by a previous call to 
name_to_handle_at() and returns an open file descriptor. 

name_to_handle_at() 

The name_to_handle_at() system call returns a file handle and a mount ID corresponding to the file speci¬ 
fied by the dirfd and pathname arguments. The file handle is returned via the argument handle, which is a 
pointer to a structure of the following form: 

struct file_handle { 

unsigned int handle_bytes; /* Size of f_handle [in, out] */ 

int handle_type; /* Handle type [out] */ 

unsigned char f_handle[0]; /* File identifier (sized by 

caller) [out] */ 

}; 

It is the caller’s responsibility to allocate the structure with a size large enough to hold the handle returned 
in fjiandle. Before the call, the handlejbytes field should be initialized to contain the allocated size for 
f_handle. (The constant MAX_HANDLE_SZ, defined in <fcntl.h>, specifies the maximum expected size 
for a file handle. It is not a guaranteed upper limit as future filesystems may require more space.) Upon 
successful return, the handle_bytes field is updated to contain the number of bytes actually written to 
f_handle. 

The caller can discover the required size for the filejiandle structure by making a call in which han¬ 
dle- >handle_bytes is zero; in this case, the call fails with the error EOVERFLOW and handle->han- 
dle_bytes is set to indicate the required size; the caller can then use this information to allocate a structure 
of the correct size (see EXAMPLE below). Some care is needed here as EOVERFLOW can also indicate 
that no file handle is available for this particular name in a filesystem which does normally support file-han¬ 
dle lookup. This case can be detected when the EOVERFLOW error is returned without handlejbytes be¬ 
ing increased. 

Other than the use of the handlejbytes field, the caller should treat the filejiandle structure as an opaque 
data type: the handleJype and fjiandle fields are needed only by a subsequent call to open_by_han- 
dle_at(). 

The flags argument is a bit mask constructed by ORing together zero or more of AT_EMPTY_PATH and 
AT_SYMLINK_FOLLOW, described below. 

Together, the pathname and dirfd arguments identify the file for which a handle is to be obtained. There 
are four distinct cases: 

* If pathname is a nonempty string containing an absolute pathname, then a handle is returned for the file 
referred to by that pathname. In this case, dirfd is ignored. 
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* If pathname is a nonempty string containing a relative pathname and dirfd has the special value 
AT_FDCWD, then pathname is interpreted relative to the current working directory of the caller, and a 
handle is returned for the file to which it refers. 

* If pathname is a nonempty string containing a relative pathname and dirfd is a file descriptor referring 
to a directory, then pathname is interpreted relative to the directory referred to by dirfd, and a handle is 
returned for the file to which it refers. (See openat(2) for an explanation of why "directory file descrip¬ 
tors" are useful.) 

* If pathname is an empty string and flags specifies the value AT_EMPTY_PATH, then dirfd can be an 
open file descriptor referring to any type of file, or AT_FDCWD, meaning the current working direc¬ 
tory, and a handle is returned for the file to which it refers. 

The mount_id argument returns an identifier for the filesystem mount that corresponds to pathname. This 
corresponds to the first field in one of the records in /proc/seif/mountinfo. Opening the pathname in the 
fifth field of that record yields a file descriptor for the mount point; that file descriptor can be used in a sub¬ 
sequent call to open_by_handle_at(). mount_id is returned both for a successful call and for a call that re¬ 
sults in the error EOYERFLOW. 

By default, name_to_handle_at() does not dereference pathname if it is a symbolic link, and thus returns a 
handle for the link itself. If AT_SYMLINK_FOLLOW is specified in flags, pathname is dereferenced if 
it is a symbolic link (so that the call returns a handle for the file referred to by the link). 

name_to_handle_at() does not trigger a mount when the final component of the pathname is an automount 
point. When a filesystem supports both file handles and automount points, a name_to_handle_at() call on 
an automount point will return with error EOYERFLOW without having increased handle_bytes. This 
can happen since Linux 4.13 with NFS when accessing a directory which is on a separate filesystem on the 
server. In this case, the automount can be triggered by adding a "/" to the end of the pathname. 

open_by_liandle_at() 

The open_by_handle_at() system call opens the file referred to by handle, a file handle returned by a pre¬ 
vious call to name_to_handle_at(). 

The mounted argument is a file descriptor for any object (file, directory, etc.) in the mounted filesystem 
with respect to which handle should be interpreted. The special value AT_FDCWD can be specified, 
meaning the current working directory of the caller. 

The flags argument is as for open(2). If handle refers to a symbolic link, the caller must specify the 
0_PATH flag, and the symbolic link is not dereferenced; the 0_N0F0LL0W flag, if specified, is ig¬ 
nored. 

The caller must have the CAP_DAC_READ_SEARCH capability to invoke open_by_handle_at(). 

RETURN VALUE 

On success, name_to_handle_at() returns 0, and open_by_handle_at() returns a nonnegative file descrip¬ 
tor. 

In the event of an error, both system calls return -1 and set ermo to indicate the cause of the error. 

ERRORS 

name_to_handle_at() and open_by_liandle_at() can fail for the same errors as openat(2). In addition, 
they can fail with the errors noted below. 

name_to_handle_at() can fail with the following errors: 

EFAULT 

pathname, mount_id, or handle points outside your accessible address space. 

EINVAL 

flags includes an invalid bit value. 

EINVAL 

handle->handleJbytes is greater than MAX_HANDLE_SZ. 
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ENOENT 

pathname is an empty string, but AT_EMPTY_PATH was not specified in flags. 

ENOTDIR 

The file descriptor supplied in dirfd does not refer to a directory, and it is not the case that both 
flags includes AT_EMPTY_PATH and pathname is an empty string. 

EOPNOTSUPP 

The filesystem does not support decoding of a pathname to a file handle. 

EOVERFLOW 

The handle->handle_bytes value passed into the call was too small. When this error occurs, han¬ 
dle- >handle_hytes is updated to indicate the required size for the handle. 

open_by_handle_at() can fail with the following errors: 

EBADF 

mount Jd is not an open file descriptor. 

EFAULT 

handle points outside your accessible address space. 

EINVAL 

handle->handle_bytes is greater than MAX_HANDLE_SZ or is equal to zero. 

ELOOP 

handle refers to a symbolic link, but 0_PATH was not specified in flags. 

EPERM 

The caller does not have the CAP_DAC_READ_SEARCH capability. 

ESTALE 

The specified handle is not valid. This error will occur if, for example, the hie has been deleted. 

VERSIONS 

These system calls first appeared in Linux 2.6.39. Library support is provided in glibc since version 2.14. 

CONFORMING TO 

These system calls are nonstandard Linux extensions. 

FreeBSD has a broadly similar pair of system calls in the form of getfh() and openfh(). 

NOTES 

A hie handle can be generated in one process using name_to_handle_at() and later used in a different 
process that calls open_by_handle_at(). 

Some hlesystem don’t support the translation of pathnames to hie handles, for example, /proc, /sys, and 
various network hlesystems. 

A hie handle may become invalid ("stale") if a hie is deleted, or for other hlesystem-specihc reasons. In¬ 
valid handles are notihed by an ESTALE error from open_by_handle_at(). 

These system calls are designed for use by user-space hie servers. For example, a user-space NFS server 
might generate a hie handle and pass it to an NFS client. Later, when the client wants to open the hie, it 
could pass the handle back to the server. This sort of functionality allows a user-space hie server to operate 
in a stateless fashion with respect to the hies it serves. 

If pathname refers to a symbolic link and flags does not specify AT_SYMLINK_FOLLOW, then 
name_to_handle_at() returns a handle for the link (rather than the hie to which it refers). The process re¬ 
ceiving the handle can later perform operations on the symbolic link by converting the handle to a hie de¬ 
scriptor using open_by_handle_at() with the 0_PATH hag, and then passing the hie descriptor as the 
dirfd argument in system calls such as readlinkat(2) and fchownat(2). 

Obtaining a persistent filesystem ID 

The mount IDs in /proc/self/mountinfo can be reused as hlesystems are unmounted and mounted. There¬ 
fore, the mount ID returned by name_to_handle_at() (in *mount_id) should not be treated as a persistent 
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identifier for the corresponding mounted filesystem. However, an application can use the information in the 
mountinfo record that corresponds to the mount ID to derive a persistent identifier. 

For example, one can use the device name in the fifth field of the mountinfo record to search for the corre¬ 
sponding device UUID via the symbolic links in /dev/disks/by-uuid. (A more comfortable way of obtain¬ 
ing the UUID is to use the Iibblkid(3) library.) That process can then be reversed, using the UUID to look 
up the device name, and then obtaining the corresponding mount point, in order to produce the mounted 
argument used by open_by_handle_at(). 

EXAMPLE 

The two programs below demonstrate the use of name_to_handle_at() and open_by_handle_at(). The 
first program ( t_name_to_handle_at.c ) uses name_to_handle_at() to obtain the file handle and mount ID 
for the file specified in its command-line argument; the handle and mount ID are written to standard output. 

The second program ( t_open_by_handle_at.c ) reads a mount ID and file handle from standard input. The 
program then employs open_by_handle_at() to open the file using that handle. If an optional command¬ 
line argument is supplied, then the mounted argument for open_by_handle_at() is obtained by opening 
the directory named in that argument. Otherwise, mount_fd is obtained by scanning /proc/self/mountinfo to 
find a record whose mount ID matches the mount ID read from standard input, and the mount directory 
specified in that record is opened. (These programs do not deal with the fact that mount IDs are not persis¬ 
tent.) 

The following shell session demonstrates the use of these two programs: 

$ echo 'Can you please think about it?' > cecilia.txt 
$ ./t_name_to_handle_at cecilia.txt > fh 
$ ./t_open_by_handle_at < fh 

open_by_handle_at: Operation not permitted 

$ sudo ./t_open_by_handle_at < fh # Need CAP_SYS_ADMIN 

Read 31 bytes 
$ rm cecilia.txt 

Now we delete and (quickly) re-create the file so that it has the same content and (by chance) the same in¬ 
ode. Nevertheless, open_by_handle_at() recognizes that the original file referred to by the file handle no 
longer exists. 

$ stat —printf="%i\n" cecilia.txt # Display inode number 

4072121 

$ rm cecilia.txt 

$ echo 'Can you please think about it?' > cecilia.txt 
$ stat —printf="%i\n" cecilia.txt # Check inode number 

4072121 

$ sudo ./t_open_by_handle_at < fh 

open_by_handle_at: Stale NFS file handle 

Program source: t_name_to_handle_at.c 

♦define _GNU_SOURCE 
♦include <sys/types.h> 

♦include <sys/stat.h> 

♦include <fcntl.h> 

♦include <stdio.h> 

♦include <stdlib.h> 

♦include <unistd.h> 

♦include <errno.h> 

♦include <string.h> 

♦define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); \ 

} while (0) 
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int 

main(int argc, char *argv[]) 

{ 

struct file_handle *fhp; 

int mount_id, fhsize, flags, dirfd, j; 

char *pathname; 

if (argc != 2) { 

fprintf(stderr, "Usage: %s pathname\n", argv[0]); 
exit(EXIT_FAILURE) ; 

} 

pathname = argv[l]; 

/* Allocate file_handle structure */ 

fhsize = sizeof(*fhp) ; 
fhp = malloc(fhsize) ; 
if (fhp == NULL) 

errExit("malloc") ; 

/* Make an initial call to name_to_handle_at() to discover 
the size required for file handle */ 

dirfd = AT_FDCWD; /* For name_to_handle_at() calls */ 

flags = 0; /* For name_to_handle_at() calls */ 

fhp->handle_bytes = 0; 

if (name_to_handle_at(dirfd, pathname, fhp, 

&mount_id, flags) != -1 || errno != EOVERFLOW) { 
fprintf(stderr, "Unexpected result from name_to_handle_at()\n"); 
exit(EXIT_FAILURE); 

} 

/* Reallocate file_handle structure with correct size */ 

fhsize = sizeof(struct file_handle) + fhp->handle_bytes; 

fhp = realloc(fhp, fhsize); /* Copies fhp->handle_bytes */ 

if (fhp == NULL) 

errExit("realloc") ; 

/* Get file handle from pathname supplied on command line */ 

if (name_to_handle_at(dirfd, pathname, fhp, &mount_id, flags) == -1) 
errExit("name_to_handle_at"); 

/* Write mount ID, file handle size, and file handle to stdout, 
for later reuse by t_open_by_handle_at.c */ 

printf("%d\n", mount_id); 

printf("%d %d ", fhp->handle_bytes, fhp->handle_type); 
for (j = 0; j < fhp->handle_bytes; j++) 
printf(" %02x", fhp->f_handle[j]) ; 
printf(" \n" ); 
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exit(EXIT_SUCCESS); 

} 

Program source: t_open_by_handle_at.c 

♦define _GNU_SOURCE 
♦include <sys/types.h> 

♦include <sys/stat.h> 

♦include <fcntl.h> 

♦include <limits.h> 

♦include <stdio.h> 

♦include <stdlib.h> 

♦include <unistd.h> 

♦include <string.h> 

♦define errExit(rasg) do { perror(msg); exit(EXIT_FAILURE); \ 

} while (0) 

/* Scan /proc/self/mountinfo to find the line whose mount ID matches 
'mount_id'. (An easier way to do this is to install and use the 
'libmount' library provided by the 'util-linux' project.) 

Open the corresponding mount path and return the resulting file 
descriptor. */ 

static int 

open_mount_path_by_id(int mount_id) 

{ 

char *linep; 
size_t lsize; 

char mount_path[PATH_MAX] ; 
int mi_mount_id, found; 
ssize_t nread; 

FILE *fp; 

fp = fopen("/proc/self/mountinfo" , "r"); 

if (fp == NULL) 

errExit("fopen"); 

found = 0; 
linep = NULL; 
while (!found) { 

nread = getline(&linep, &lsize, fp); 
if (nread == -1) 
break; 

nread = sscanf(linep, "%d %*d %*s %*s %s", 

&mi_mount_id, mount_path); 
if (nread != 2) { 

fprintf(stderr, "Bad sscanf()\n"); 
exit(EXIT_FAILURE) ; 

} 

if (mi_mount_id == mount_id) 
found = 1; 

} 
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free(linep); 
fclose(fp); 
if (!found) { 

fprintf (stderr, "Could not find mount pointin''); 
exit(EXIT_FAILURE) ; 

} 

return open(mount_path, 0_RD0NLY) ; 

} 

int 

main(int argc, char *argv[]) 

{ 

struct file_handle *fhp; 

int mount_id, fd, mount_fd, handle_bytes, j; 
ssize_t nread; 
char buf[1000] ; 

#define LINE_SIZE 100 

char linel[LINE_SIZE], line2[LINE_SIZE]; 
char *nextp; 

if ((argc > 1 && strcmp(argv[1], "—help") == 0) || argc > 2) { 

fprintf(stderr, "Usage: %s [mount-path]\n", argv[0]); 
exit(EXIT_FAILURE); 

} 

/* Standard input contains mount ID and file handle information: 

Line 1: <mount_id> 

Line 2: <handle_bytes> <handle_type> <bytes of handle in hex> 

*/ 

if ((fgets(linel, sizeof(linel), stdin) == NULL) \ 

(fgets(line2, sizeof(line2), stdin) == NULL)) { 
fprintf(stderr, "Missing mount_id / file handlein"); 
exit(EXIT_FAILURE) ; 

} 

mount_id = atoi(linel); 

handle_bytes = strtoul(line2, Snextp, 0); 

/* Given handle_bytes, we can now allocate file_handle structure */ 

fhp = malloc(sizeof(struct file_handle) + handle_bytes); 
if (fhp == NULL) 

errExit("malloc") ; 

fhp->handle_bytes = handle_bytes; 

fhp->handle_type = strtoul (nextp, Snextp, 0); 
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for (j = 0; j < fhp->handle_bytes; j++) 

fhp->f_handle[j] = strtoul(nextp, Snextp, 16); 

/* Obtain file descriptor for mount point, either by opening 
the pathname specified on the command line, or by scanning 
/proc/self/mounts to find a mount that matches the 'mount_id' 
that we received from stdin. */ 

if (argc > 1) 

mount_fd = open(argv[1], 0_RD0NLY); 

else 

mount_fd = open_mount_path_by_id(mount_id); 

if (mount_fd == -1) 

errExit("opening mount fd"); 

/* Open file using handle and mount point */ 

fd = open_by_handle_at(mount_fd, fhp, 0_RD0NLY); 
if (fd == -1) 

errExit("open_by_handle_at"); 

/* Try reading a few bytes from the file */ 

nread = read(fd, buf, sizeof(buf)) ; 
if (nread == -1) 

errExit("read"); 

printf("Read %zd bytes\n", nread); 
exit(EXIT_SUCCESS); 

} 

SEE ALSO 

open(2), libblkid(3), blkid(8), findfs(8), mount(8) 

The libblkid and libmount documentation in the latest util-linux release at 

(https://www.kernel.org/pub/linux/utils/util-linux/) 

COLOPHON 

This page is part of release 5.02 of the Linux man-pages project. A description of the project, information 
about reporting bugs, and the latest version of this page, can be found at 
https://www.kernel.org/doc/man-pages/. 
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